home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / OSA.idl < prev    next >
Text File  |  1996-05-01  |  39KB  |  1,060 lines
  1. /*
  2.      File:        OSA.idl
  3.  
  4.      Contains:    AppleScript Client Interfaces.
  5.  
  6.      Version:    Technology:    AppleScript 1.1
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __OSA_IDL__
  19. #define __OSA_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __ERRORS_IDL__
  25. #include <Errors.idl>
  26. #endif
  27. #ifndef __APPLEEVENTS_IDL__
  28. #include <AppleEvents.idl>
  29. #endif
  30. #ifndef __AEOBJECTS_IDL__
  31. #include <AEObjects.idl>
  32. #endif
  33. #ifndef __COMPONENTS_IDL__
  34. #include <Components.idl>
  35. #endif
  36.  
  37. #ifdef __SOMIDL__
  38.  
  39. #if FOR_SYSTEM7_ONLY
  40. /*
  41. *************************************************************************
  42.     Types and Constants
  43. *************************************************************************
  44. */
  45. /*
  46.     The componenent manager type code for components that
  47.         support the OSA interface defined here. 
  48. */
  49. /* 0x6f736120 */
  50. /* 0x73637074 */
  51. /*    Type of script document files.    */
  52. /* 0x6f736173 */
  53. /*
  54.         Suite and event code of the RecordedText event. 
  55.         (See OSAStartRecording, below.)
  56. */
  57. /* 0x61736372 */
  58. /* 0x72656364 */
  59. /* Selector returns boolean */
  60. /* 0x6d6f6469 */
  61. /* Selector returns boolean */
  62. /* 0x63736372 */
  63. /* Selector returns boolean */
  64. /* 0x76616c75 */
  65. /* Selector returns boolean */
  66. /* 0x636e7478 */
  67. /* Selector returns a DescType which may be passed to OSACoerceToDesc */
  68. /* 0x62657374 */
  69. /*
  70.         This selector is used to determine whether a script has source 
  71.         associated with it that when given to OSAGetSource, the call will not
  72.         fail.  The selector returns a boolean.
  73. */
  74. /* 0x67737263 */
  75. typedef ComponentResult            OSAError;
  76.  
  77. /* Under the Open Scripting Architecture all error results are longs */
  78. typedef unsigned long            OSAID;
  79.  
  80. /*
  81.         OSAIDs allow transparent manipulation of scripts associated with
  82.          various scripting systems.
  83. */
  84. /* No -script constant. */
  85. /*
  86.         Some routines take flags that control their execution.  This constant
  87.         declares default mode settings are used.
  88. */
  89. typedef OpaquePtr OSACreateAppleEventProcPtr;
  90. typedef OpaquePtr OSACreateAppleEventUPP;
  91. typedef OpaquePtr OSASendProcPtr;
  92. typedef OpaquePtr OSASendUPP;
  93. /*
  94. *************************************************************************
  95.     Standard Script Errors
  96. **************************************************************************
  97.     It is recommended that scripting components use the following set of error
  98.     codes to signal failure when applicable.  This enables applications that
  99.     use the OSA API to deal with some class of script errors in a less than 
  100.     ad hoc manner.  Scripting components are of course encouraged to return
  101.     component-specific errors when these don't apply.
  102. *************************************************************************
  103. */
  104. /*
  105.         Dynamic errors:
  106.  
  107.     These errors result from data-dependent conditions and are typically
  108.     signaled at runtime.
  109. */
  110. /*
  111.         Signaled when a value can't be coerced to the desired type. Similar
  112.           to errOSATypeError except results from coercion.
  113. */
  114. /* Signaled when an object is not found in a container */
  115. /*
  116.         Signaled when an object cannot be set in a container.  Same as 
  117.           AERegistry error errAEWriteDenied.
  118. */
  119. /*
  120.         Signaled by user scripts or applications when no actual error code
  121.           is to be returned.  Simply means "an error has occurred".  Most useful
  122.           in conjunction with an error message from the application.
  123. */
  124. /* Signaled when there is an attempt to divide by zero */
  125. /* Signaled when integer or real value is too large to be represented */
  126. /*
  127.         Signaled when application can't be launched or when it is remote and
  128.           program linking is not enabled.
  129. */
  130. /* Signaled when an application can't respond to AppleEvents */
  131. /* Signaled when an application's terminology resource is not readable */
  132. /* Signaled when the runtime stack overflows */
  133. /* Signaled when a runtime internal data structure overflows */
  134. /*
  135.         Signaled when an intrinsic limitation is exceeded for the size of 
  136.           a value or data structure.
  137. */
  138. /*
  139.         Component-specific dynamic script errors:
  140.  
  141.     The range -2720 thru -2739 is reserved for component-specific runtime errors.
  142.     (Note that error codes from different scripting components in this range will
  143.     overlap.)
  144. */
  145. /*
  146.         Static errors:
  147.  
  148.     These errors comprise what are commonly thought of as parse and compile-
  149.     time errors.  However, in a dynamic system (e.g. AppleScript) any or all
  150.     of these may also occur at runtime.
  151. */
  152. /* Signaled when data was not the right type and coercion is not allowed */
  153. /* Signaled when a message was sent to an object that didn't handle it */
  154. /*
  155.         Signaled when a function to be returned doesn't exist.  (Probably only
  156.           useful in languages with first-class functions that distinguish between
  157.           functions and other values (two name spaces). This is different from
  158.           errOSAMessageNotUnderstood, which may be signaled when the method is
  159.           invoked.
  160. */
  161. /* Signaled when a container can never have the requested object */
  162. /* Signaled when index was out of range. Specialization of errOSACantAccess. */
  163. /* Signaled when a range is screwy. Specialization of errOSACantAccess. */
  164. /*
  165.         Signaled when an object can never be set in a container.  Same as 
  166.           AERegistry error errAENotModifiable.
  167. */
  168. /*
  169.         Signaled when a syntax error occurs. (e.g. "Syntax error" or
  170.          "<this> can't go after <that>").
  171. */
  172. /*
  173.         Signaled when another form of syntax was expected. (e.g. "expected
  174.           a <type> but found <this>").
  175. */
  176. /* Signaled when a name or number is too long to be parsed */
  177. /*
  178.         Signaled when a parameter is missing for a function invocation.  Note
  179.           that in some languages, this error may occur at runtime.
  180. */
  181. /*
  182.         Signaled when function is called with the wrong number of parameters,
  183.           or a parameter pattern cannot be matched.
  184. */
  185. /*
  186.         Signaled when a formal parameter, local variable, or instance variable
  187.           is specified more than once.
  188. */
  189. /*
  190.         Signaled when a formal parameter, local variable, or instance variable
  191.           is specified more than once.
  192. */
  193. /*
  194.         Signaled when more than one handler is defined with the same name in 
  195.           a scope where the language doesn't allow it.
  196. */
  197. /* Signaled when a variable is accessed that has no value */
  198. /*
  199.         Signaled when a variable is declared inconsistently in the same scope,
  200.           such as both local and global.
  201. */
  202. /*
  203.         Signaled when illegal control flow occurs in an application (no catcher
  204.           for throw, non-lexical loop exit, etc.).
  205. */
  206. /*
  207.         Component-specific static script errors:
  208.  
  209.     The range -2760 thru -2779 is reserved for component-specific parsing and
  210.     compile-time errors. (Note that error codes from different scripting
  211.     components in this range will overlap.)
  212. */
  213. /*
  214.         Dialect-specific script errors:
  215.  
  216.     The range -2780 thru -2799 is reserved for dialect specific error codes for
  217.     scripting components that support dialects. (Note that error codes from
  218.     different scripting components in this range will overlap, as well as error
  219.     codes from different dialects in the same scripting component.)
  220. */
  221. /*
  222. *************************************************************************
  223.     OSA Interface Descriptions
  224. **************************************************************************
  225.     The OSA Interface is broken down into a required interface, and several
  226.     optional interfaces to support additional functionality.  A given scripting
  227.     component may choose to support only some of the optional interfaces in
  228.     addition to the basic interface.  The OSA Component Flags may be used to 
  229.     query the Component Manager to find a scripting component with a particular
  230.     capability, or determine if a particular scripting component supports a 
  231.     particular capability.
  232. *************************************************************************
  233. */
  234. /* OSA Component Flags: */
  235. /* Component Selectors: */
  236. /* Compiling: */
  237. /* GetSource: */
  238. /* AECoercion: */
  239. /* AESending: */
  240. /* Recording: */
  241. /* Convenience: */
  242. /* Dialects: */
  243. /* Event Handling: */
  244. /* scripting component specific selectors are added beginning with this value  */
  245. /*
  246.         Mode Flags:
  247.  
  248.     Warning: These should not conflict with the AESend mode flags in
  249.     AppleEvents.h, because we may want to use them as OSA mode flags too.
  250. */
  251. /*
  252.         This mode flag may be passed to OSALoad, OSAStore or OSACompile to
  253.           instruct the scripting component to not retain the "source" of an
  254.           expression.  This will cause the OSAGetSource call to return the error
  255.           errOSASourceNotAvailable if used.  However, some scripting components
  256.           may not retain the source anyway.  This is mainly used when either space
  257.           efficiency is desired, or a script is to be "locked" so that its
  258.           implementation may not be viewed.
  259. */
  260. /*
  261.         These mode flags may be passed to OSACompile, OSAExecute, OSALoadExecute
  262.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  263.           indicate whether or not the script may interact with the user, switch
  264.           layer or reconnect if necessary.  Any AppleEvents will be sent with the
  265.           corresponding AESend mode supplied.
  266. */
  267. /*
  268.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  269.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  270.           indicate whether or not AppleEvents should be sent with the
  271.           kAECanSwitchLayer mode flag sent or not. NOTE: This flag is exactly the
  272.           opposite sense of the AppleEvent flag kAECanSwitchLayer.  This is to
  273.           provide a more convenient default, i.e. not supplying any mode
  274.           (kOSAModeNull) means to send events with kAECanSwitchLayer.  Supplying
  275.           the kOSAModeCantSwitchLayer mode flag will cause AESend to be called
  276.           without kAECanSwitchLayer.
  277. */
  278. /*
  279.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  280.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  281.           indicate whether or not AppleEvents should be sent with the kAEDontRecord
  282.           mode flag sent or not. NOTE: This flag is exactly the opposite sense of
  283.           the AppleEvent flag kAEDontRecord.  This is to provide a more convenient
  284.           default, i.e. not supplying any mode (kOSAModeNull) means to send events
  285.           with kAEDontRecord.  Supplying the kOSAModeDoRecord mode flag will 
  286.           cause AESend to be called without kAEDontRecord.
  287. */
  288. /*
  289.         This is a mode flag for OSACompile that indicates that a context should
  290.           be created as the result of compilation. All handler definitions are
  291.           inserted into the new context, and variables are initialized by
  292.           evaluating their initial values in a null context (i.e. they must be
  293.           constant expressions).
  294. */
  295. /*
  296.         This is a mode flag for OSACompile that indicates that the previous
  297.           script ID (input to OSACompile) should be augmented with any new
  298.           definitions in the sourceData rather than replaced with a new script.
  299.           This means that the previous script ID must designate a context.
  300.           The presence of this flag causes the kOSAModeCompileIntoContext flag
  301.           to be implicitly used, causing any new definitions to be initialized
  302.           in a null context.
  303. */
  304. /*
  305.         This mode flag may be passed to OSADisplay or OSADoScript to indicate
  306.           that output only need be human-readable, not re-compilable by OSACompile.
  307.           If used, output may be arbitrarily "beautified", e.g. quotes may be left
  308.           off of string values, long lists may have elipses, etc.
  309. */
  310. /*
  311.         This mode flag may be passed to OSAStore in the case where the scriptID
  312.           is a context.  This causes the context to be saved, but not the context's
  313.           parent context.  When the stored context is loaded back in, the parent
  314.           will be kOSANullScript.
  315. */
  316. /*
  317.         This mode flag may be passed to OSAExecuteEvent to cause the event to
  318.           be dispatched to the direct object of the event. The direct object (or
  319.           subject attribute if the direct object is a non-object specifier) will
  320.           be resolved, and the resulting script object will be the recipient of
  321.           the message. The context argument to OSAExecuteEvent will serve as the
  322.           root of the lookup/resolution process.
  323. */
  324. /*
  325.         This mode flag may be passed to OSAExecuteEvent to indicate that
  326.           components do not have to get the data of object specifier arguments.
  327. */
  328. /*
  329. *************************************************************************
  330.     OSA Basic Scripting Interface
  331. **************************************************************************
  332.     Scripting components must at least support the Basic Scripting interface.
  333. *************************************************************************
  334. */
  335. /*
  336.         Loading and Storing Scripts:
  337.  
  338.     These routines allow scripts to be loaded and stored in their internal
  339.     (possibly compiled, non-text) representation.
  340. */
  341. /* Resource type for scripts */
  342. /*
  343.         Default type given to OSAStore which creates "generic" loadable script
  344.           data descriptors.
  345. */
  346. /*
  347.         OSAComponentFunctionInline(kOSASelectLoad, 12);
  348.     
  349.         Errors:
  350.             badComponentInstance        invalid scripting component instance
  351.             errOSASystemError
  352.             errOSABadStorageType:        scriptData not for this scripting component
  353.             errOSACorruptData:            data seems to be corrupt
  354.             errOSADataFormatObsolete    script data format is no longer supported
  355.             errOSADataFormatTooNew        script data format is from a newer version
  356.         
  357.         ModeFlags:
  358.             kOSAModePreventGetSource
  359. */
  360. /*
  361.         OSAComponentFunctionInline(kOSASelectStore, 16);
  362.     
  363.         Errors:
  364.             badComponentInstance    invalid scripting component instance
  365.             errOSASystemError
  366.             errOSAInvalidID
  367.             errOSABadStorageType:    desiredType not for this scripting component
  368.         
  369.         ModeFlags:
  370.             kOSAModePreventGetSource
  371.             kOSAModeDontStoreParent
  372. */
  373. /* Executing Scripts: */
  374. /*
  375.         OSAComponentFunctionInline(kOSASelectExecute, 16);
  376.         This call runs a script.  The contextID represents the environment
  377.         with which global variables in the script are resolved.  The constant
  378.         kOSANullScript may be used for the contextID if the application wishes
  379.         to not deal with context directly (a default one is associated with each
  380.         scripting component instance).  The resultingScriptValueID is the 
  381.         result of evaluation, and contains a value which may be displayed using
  382.         the OSAGetSource call.  The modeFlags convey scripting component
  383.         specific information.
  384.     
  385.         Errors:
  386.             badComponentInstance    invalid scripting component instance
  387.             errOSASystemError
  388.             errOSAInvalidID
  389.             errOSAScriptError:        the executing script got an error
  390.     
  391.         ModeFlags:
  392.             kOSAModeNeverInteract
  393.             kOSAModeCanInteract
  394.             kOSAModeAlwaysInteract
  395.             kOSAModeCantSwitchLayer
  396.             kOSAModeDontReconnect
  397.             kOSAModeDoRecord
  398. */
  399. /* Displaying results: */
  400. /*
  401.         OSAComponentFunctionInline(kOSASelectDisplay, 16);
  402.         This call is used to convert results (script value IDs) into displayable
  403.         text. The desiredType should be at least typeChar, and modeFlags are
  404.         scripting system specific flags to control the formatting of the
  405.         resulting text. This call differs from OSAGetSource in that (1) it
  406.         always produces at least typeChar, (2) is only works on script values,
  407.         (3) it may display it's output in non-compilable form (e.g. without
  408.         string quotes, elipses inserted in long and/or circular lists, etc.) and
  409.         (4) it is required by the basic scripting interface.
  410.     
  411.         Errors:
  412.             badComponentInstance    invalid scripting component instance
  413.             errOSASystemError
  414.             errOSAInvalidID
  415.             errAECoercionFail:        desiredType not supported by scripting component
  416.     
  417.         ModeFlags:
  418.             kOSAModeDisplayForHumans
  419. */
  420. /* Getting Error Information: */
  421. /*
  422.         OSAComponentFunctionInline(kOSASelectScriptError, 12);
  423.         Whenever script execution returns errOSAExecutionError, this routine
  424.         may be used to get information about that error.  The selector describes
  425.         the type of information desired about the error (various selectors are
  426.         listed below).  The desiredType indicates the data type of the result
  427.         desired for that selector.
  428.     
  429.         Errors:
  430.             badComponentInstance    invalid scripting component instance
  431.             errOSASystemError
  432.             errOSABadSelector:        selector not supported by scripting component
  433.             errAECoercionFail:        desiredType not supported by scripting component
  434. */
  435. /* OSAScriptError selectors: */
  436. /*
  437.         This selector is used to determine the error number of a script error.
  438.         These error numbers may be either system error numbers, or error numbers
  439.         that are scripting component specific.
  440.         Required desiredTypes:    
  441.               typeShortInteger
  442. */
  443. /*
  444.         This selector is used to determine the full error message associated
  445.         with the error number.  It should include the name of the application
  446.         which caused the error, as well as the specific error that occurred.
  447.         This selector is sufficient for simple error reporting (but see
  448.         kOSAErrorBriefMessage, below).
  449.         Required desiredTypes:
  450.             typeChar                    error message string
  451. */
  452. /*
  453.         This selector is used to determine a brief error message associated with
  454.         the error number.  This message and should not mention the name of the
  455.         application which caused the error, any partial results or offending
  456.         object (see kOSAErrorApp, kOSAErrorPartialResult and
  457.         kOSAErrorOffendingObject, below).
  458.         Required desiredTypes:
  459.               typeChar                    brief error message string
  460. */
  461. /*  0x65727262  */
  462. /*
  463.         This selector is used to determine which application actually got the
  464.         error (if it was the result of an AESend), or the current application
  465.         if ....
  466.         Required desiredTypes:
  467.               typeProcessSerialNumber        PSN of the errant application
  468.               typeChar                    name of the errant application
  469. */
  470. /*  0x65726170  */
  471. /*
  472.         This selector is used to determine any partial result returned by an 
  473.         operation. If an AESend call failed, but a partial result was returned,
  474.         then the partial result may be returned as an AEDesc.
  475.         Required desiredTypes:
  476.               typeBest                    AEDesc of any partial result
  477. */
  478. /*  0x70746c72   */
  479. /*
  480.         This selector is used to determine any object which caused the error
  481.         that may have been indicated by an application.  The result is an 
  482.         AEDesc.
  483.         Required desiredTypes:
  484.               typeBest                    AEDesc of any offending object
  485. */
  486. /*  0x65726f62   */
  487. /*
  488.         This selector is used to determine the type expected by a coercion 
  489.         operation if a type error occurred.
  490. */
  491. /*  0x65727274   */
  492. /*
  493.         This selector is used to determine the source text range (start and 
  494.         end positions) of where the error occurred.
  495.         Required desiredTypes:
  496.               typeOSAErrorRange
  497. */
  498. /*  0x65726e67  */
  499. /*
  500.         An AERecord type containing keyOSASourceStart and keyOSASourceEnd fields
  501.         of type short.
  502. */
  503. /*  0x65726e67   */
  504. /* Field of a typeOSAErrorRange record of typeShortInteger */
  505. /*  0x73726373    */
  506. /* Field of a typeOSAErrorRange record of typeShortInteger */
  507. /*  0x73726365   */
  508. /* Disposing Script IDs: */
  509. /*
  510.         OSAComponentFunctionInline(kOSASelectDispose, 4);
  511.         Disposes a script or context.
  512.     
  513.         Errors:
  514.             badComponentInstance    invalid scripting component instance
  515.             errOSASystemError
  516.             errOSAInvalidID
  517. */
  518. /* Getting and Setting Script Information: */
  519. /*
  520.         OSAComponentFunctionInline(kOSASelectSetScriptInfo, 12);
  521.     
  522.         Errors:
  523.             badComponentInstance    invalid scripting component instance
  524.             errOSASystemError
  525.             errOSAInvalidID
  526.             errOSABadSelector:        selector not supported by scripting component
  527.                                     or selector not for this scriptID
  528. */
  529. /*
  530.         OSAComponentFunctionInline(kOSASelectGetScriptInfo, 12);
  531.     
  532.         Errors:
  533.             badComponentInstance    invalid scripting component instance
  534.             errOSASystemError
  535.             errOSAInvalidID
  536.             errOSABadSelector:        selector not supported by scripting component
  537.                                     or selector not for this scriptID
  538. */
  539. /*
  540.  Manipulating the ActiveProc:
  541.  
  542.     Scripting systems will supply default values for these procedures if they
  543.     are not set by the client:
  544. */
  545. typedef OpaquePtr OSAActiveProcPtr;
  546. typedef OpaquePtr OSAActiveUPP;
  547. /*
  548.         OSAComponentFunctionInline(kOSASelectSetActiveProc, 8);
  549.         If activeProc is nil, the default activeProc is used.
  550.     
  551.         Errors:
  552.             badComponentInstance    invalid scripting component instance
  553.             errOSASystemError
  554. */
  555. /*
  556.         OSAComponentFunctionInline(kOSASelectGetActiveProc, 8);
  557.     
  558.         Errors:
  559.             badComponentInstance    invalid scripting component instance
  560.             errOSASystemError
  561. */
  562. /*
  563. *************************************************************************
  564.     OSA Optional Compiling Interface
  565. **************************************************************************
  566.     Scripting components that support the Compiling interface have the 
  567.     kOSASupportsCompiling bit set in it's ComponentDescription.
  568. *************************************************************************
  569. */
  570. /*
  571.         OSAComponentFunctionInline(kOSASelectScriptingComponentName, 4);
  572.         Given a scripting component, this routine returns the name of that
  573.         scripting component in a type that is coercable to text (typeChar).
  574.         The generic scripting component returns the name of the default
  575.         scripting component.  This name should be sufficient to convey to the
  576.         user the kind of script (syntax) he is expected to write.
  577.     
  578.         Errors:
  579.             badComponentInstance    invalid scripting component instance
  580.             errOSASystemError
  581. */
  582. /*
  583.         OSAComponentFunctionInline(kOSASelectCompile, 12);
  584.         Coerces input desc (possibly text) into a script's internal format.
  585.         Once compiled, the script is ready to run.  The modeFlags convey
  586.         scripting component specific information.  The previous script ID
  587.         (result parameter) is made to refer to the newly compiled script,
  588.         unless it was originally kOSANullScript.  In this case a new script
  589.         ID is created and used.
  590.     
  591.         Errors:
  592.             badComponentInstance    invalid scripting component instance
  593.             errOSASystemError
  594.             errAECoercionFail:        sourceData is not compilable
  595.             errOSAScriptError:        sourceData was a bad script (syntax error)
  596.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  597.                                     valid on input
  598.     
  599.         ModeFlags:
  600.             kOSAModePreventGetSource
  601.             kOSAModeCompileIntoContext
  602.             kOSAModeAugmentContext
  603.             kOSAModeNeverInteract
  604.             kOSAModeCanInteract
  605.             kOSAModeAlwaysInteract
  606.             kOSAModeCantSwitchLayer
  607.             kOSAModeDontReconnect
  608.             kOSAModeDoRecord
  609. */
  610. /*
  611.         OSAComponentFunctionInline(kOSASelectCopyID, 8);
  612.         If toID is a reference to kOSANullScript then it is updated to have a
  613.         new scriptID value.  This call can be used to perform undo or revert
  614.         operations on scripts. 
  615.     
  616.         Errors:
  617.             badComponentInstance    invalid scripting component instance
  618.             errOSASystemError
  619.             errOSAInvalidID
  620. */
  621. /*
  622. *************************************************************************
  623.     OSA Optional GetSource Interface
  624. **************************************************************************
  625.     Scripting components that support the GetSource interface have the 
  626.     kOSASupportsGetSource bit set in it's ComponentDescription.
  627. *************************************************************************
  628. */
  629. /*
  630.         OSAComponentFunctionInline(kOSASelectGetSource, 12);
  631.         This routine causes a compiled script to be output in a form (possibly
  632.         text) such that it is suitable to be passed back to OSACompile.
  633.  
  634.         Errors:
  635.             badComponentInstance    invalid scripting component instance
  636.             errOSASystemError
  637.             errOSAInvalidID
  638.             errOSASourceNotAvailable    can't get source for this scriptID
  639. */
  640. /*
  641. *************************************************************************
  642.     OSA Optional AECoercion Interface
  643. **************************************************************************
  644.     Scripting components that support the AECoercion interface have the 
  645.     kOSASupportsAECoercion bit set in it's ComponentDescription.
  646. *************************************************************************
  647. */
  648. /*
  649.         OSAComponentFunctionInline(kOSASelectCoerceFromDesc, 12);
  650.         This routine causes script data to be coerced into a script value.
  651.         If the scriptData is an AppleEvent, then the resultingScriptID is a
  652.         compiled script ID (mode flags for OSACompile may be used in this case).
  653.         Other scriptData descriptors create script value IDs.
  654.     
  655.         Errors:
  656.             badComponentInstance    invalid scripting component instance
  657.             errOSASystemError
  658.     
  659.         ModeFlags:
  660.             kOSAModePreventGetSource
  661.             kOSAModeCompileIntoContext
  662.             kOSAModeNeverInteract
  663.             kOSAModeCanInteract
  664.             kOSAModeAlwaysInteract
  665.             kOSAModeCantSwitchLayer
  666.             kOSAModeDontReconnect
  667.             kOSAModeDoRecord
  668. */
  669. /*
  670.         OSAComponentFunctionInline(kOSASelectCoerceToDesc, 16);
  671.         This routine causes a script value to be coerced into any desired form.
  672.         If the scriptID denotes a compiled script, then it may be coerced to 
  673.         typeAppleEvent.
  674.     
  675.         Errors:
  676.             badComponentInstance    invalid scripting component instance
  677.             errOSASystemError
  678.             errOSAInvalidID
  679. */
  680. /*
  681. *************************************************************************
  682.     OSA Optional AESending Interface
  683. **************************************************************************
  684.     Scripting components that support the AESending interface have the 
  685.     kOSASupportsAESending bit set in it's ComponentDescription.
  686. *************************************************************************
  687. */
  688. /*
  689.     Scripting systems will supply default values for these procedures if they
  690.     are not set by the client:
  691. */
  692. /*
  693.         OSAComponentFunctionInline(kOSASelectSetSendProc, 8);
  694.         If sendProc is nil, the default sendProc is used.
  695.     
  696.         Errors:
  697.             badComponentInstance    invalid scripting component instance
  698.             errOSASystemError
  699. */
  700. /*
  701.         OSAComponentFunctionInline(kOSASelectGetSendProc, 8);
  702.     
  703.         Errors:
  704.             badComponentInstance    invalid scripting component instance
  705.             errOSASystemError
  706. */
  707. /*
  708.         OSAComponentFunctionInline(kOSASelectSetCreateProc, 8);
  709.         If createProc is nil, the default createProc is used.
  710.     
  711.         Errors:
  712.             badComponentInstance    invalid scripting component instance
  713.             errOSASystemError
  714. */
  715. /*
  716.         OSAComponentFunctionInline(kOSASelectGetCreateProc, 8);
  717.     
  718.         Errors:
  719.             badComponentInstance    invalid scripting component instance
  720.             errOSASystemError
  721. */
  722. /*
  723.         OSAComponentFunctionInline(kOSASelectSetDefaultTarget, 4);
  724.         This routine sets the default target application for AE sending.
  725.         It also establishes the default target from which terminologies come.
  726.         It is effectively like having an AppleScript "tell" statement around
  727.         the entire program.  If this routine is not called, or if the target 
  728.         is a null AEDesc, then the current application is the default target.
  729.     
  730.         Errors:
  731.             badComponentInstance    invalid scripting component instance
  732.             errOSASystemError
  733. */
  734. /*
  735. *************************************************************************
  736.     OSA Optional Recording Interface
  737. **************************************************************************
  738.     Scripting components that support the Recording interface have the 
  739.     kOSASupportsRecording bit set in it's ComponentDescription.
  740. *************************************************************************
  741. */
  742. /*
  743.         OSAComponentFunctionInline(kOSASelectStartRecording, 4);
  744.         Starts recording.  If compiledScriptToModifyID is kOSANullScript, a
  745.         new script ID is created and returned.  If the current application has
  746.         a handler for the kOSARecordedText event, then kOSARecordedText events
  747.         are sent to the application containing the text of each AppleEvent 
  748.         recorded.
  749.     
  750.         Errors:
  751.             badComponentInstance    invalid scripting component instance
  752.             errOSASystemError
  753.             errOSAInvalidID
  754.             errOSARecordingIsAlreadyOn
  755. */
  756. /*
  757.         OSAComponentFunctionInline(kOSASelectStopRecording, 4);
  758.         If compiledScriptID is not being recorded into or recording is not
  759.         currently on, no error is returned.
  760.     
  761.         Errors:
  762.             badComponentInstance    invalid scripting component instance
  763.             errOSASystemError
  764.             errOSAInvalidID
  765. */
  766. /*
  767. *************************************************************************
  768.     OSA Optional Convenience Interface
  769. **************************************************************************
  770.     Scripting components that support the Convenience interface have the 
  771.     kOSASupportsConvenience bit set in it's ComponentDescription.
  772. *************************************************************************
  773. */
  774. /*
  775.         OSAComponentFunctionInline(kOSASelectLoadExecute, 16);
  776.         This routine is effectively equivalent to calling OSALoad followed by
  777.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  778.         resulting value ID is retained.
  779.     
  780.         Errors:
  781.             badComponentInstance        invalid scripting component instance
  782.             errOSASystemError
  783.             errOSABadStorageType:        scriptData not for this scripting component
  784.             errOSACorruptData:            data seems to be corrupt
  785.             errOSADataFormatObsolete    script data format is no longer supported
  786.             errOSADataFormatTooNew        script data format is from a newer version
  787.             errOSAInvalidID
  788.             errOSAScriptError:            the executing script got an error
  789.     
  790.         ModeFlags:
  791.             kOSAModeNeverInteract
  792.             kOSAModeCanInteract
  793.             kOSAModeAlwaysInteract
  794.             kOSAModeCantSwitchLayer
  795.             kOSAModeDontReconnect
  796.             kOSAModeDoRecord
  797. */
  798. /*
  799.         OSAComponentFunctionInline(kOSASelectCompileExecute, 16);
  800.         This routine is effectively equivalent to calling OSACompile followed by
  801.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  802.         resulting value ID is retained.
  803.     
  804.         Errors:
  805.             badComponentInstance    invalid scripting component instance
  806.             errOSASystemError
  807.             errAECoercionFail:        sourceData is not compilable
  808.             errOSAScriptError:        sourceData was a bad script (syntax error)
  809.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  810.                                     valid on input
  811.             errOSAScriptError:        the executing script got an error
  812.     
  813.         ModeFlags:
  814.             kOSAModeNeverInteract
  815.             kOSAModeCanInteract
  816.             kOSAModeAlwaysInteract
  817.             kOSAModeCantSwitchLayer
  818.             kOSAModeDontReconnect
  819.             kOSAModeDoRecord
  820. */
  821. /*
  822.         OSAComponentFunctionInline(kOSASelectDoScript, 20);
  823.         This routine is effectively equivalent to calling OSACompile followed by
  824.         OSAExecute and then OSADisplay.  After execution, the compiled source
  825.         and the resulting value are is disposed.  Only the resultingText
  826.         descriptor is retained.  If a script error occur during processing, the 
  827.         resultingText gets the error message of the error, and errOSAScriptError
  828.         is returned.  OSAScriptError may still be used to extract more 
  829.         information about the particular error.
  830.     
  831.         Errors:
  832.             badComponentInstance    invalid scripting component instance
  833.             errOSASystemError
  834.             errAECoercionFail:        sourceData is not compilable or 
  835.                                     desiredType not supported by scripting component
  836.             errOSAScriptError:        sourceData was a bad script (syntax error)
  837.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  838.                                     valid on input
  839.             errOSAScriptError:        the executing script got an error
  840.     
  841.         ModeFlags:
  842.             kOSAModeNeverInteract
  843.             kOSAModeCanInteract
  844.             kOSAModeAlwaysInteract
  845.             kOSAModeCantSwitchLayer
  846.             kOSAModeDontReconnect
  847.             kOSAModeDoRecord
  848.             kOSAModeDisplayForHumans
  849. */
  850. /*
  851. *************************************************************************
  852.     OSA Optional Dialects Interface
  853. **************************************************************************
  854.     Scripting components that support the Dialects interface have the 
  855.     kOSASupportsDialects bit set in it's ComponentDescription.
  856. *************************************************************************
  857. */
  858. /*
  859.     These calls allows an scripting component that supports different dialects
  860.     to dynamically switch between those dialects.  Although this interface is
  861.     specified, the particular dialect codes are scripting component dependent.
  862. */
  863. /*
  864.         OSAComponentFunctionInline(kOSASelectSetCurrentDialect, 2);
  865.     
  866.         Errors:
  867.             badComponentInstance    invalid scripting component instance
  868.             errOSASystemError
  869.             errOSANoSuchDialect:    invalid dialectCode
  870. */
  871. /*
  872.         OSAComponentFunctionInline(kOSASelectGetCurrentDialect, 4);
  873.     
  874.         Errors:
  875.             badComponentInstance    invalid scripting component instance
  876.             errOSASystemError
  877. */
  878. /*
  879.         OSAComponentFunctionInline(kOSASelectAvailableDialects, 4);
  880.         This call return an AEList containing information about each of the
  881.         currently available dialects of a scripting component.  Each item
  882.         is an AERecord of typeOSADialectInfo that contains at least the fields
  883.         keyOSADialectName, keyOSADialectCode, KeyOSADialectLangCode and 
  884.         keyOSADialectScriptCode.
  885.     
  886.         Errors:
  887.             badComponentInstance    invalid scripting component instance
  888.             errOSASystemError
  889. */
  890. /*
  891.         OSAComponentFunctionInline(kOSASelectGetDialectInfo, 10);
  892.         This call gives information about the specified dialect of a scripting
  893.         component. It returns an AEDesc whose type depends on the selector 
  894.         specified. Available selectors are the same as the field keys for a
  895.         dialect info record. The type of AEDesc returned is the same as the 
  896.         type of the field that has same key as the selector.
  897.     
  898.         Errors:
  899.             badComponentInstance    invalid scripting component instance
  900.             errOSASystemError
  901.              errOSABadSelector
  902.             errOSANoSuchDialect:    invalid dialectCode
  903. */
  904. /*
  905.         OSAComponentFunctionInline(kOSASelectAvailableDialectCodeList, 4);
  906.         This is alternative to OSAGetAvailableDialectCodeList. Use this call
  907.         and  OSAGetDialectInfo to get information on dialects.
  908.         This call return an AEList containing dialect code for each of the
  909.         currently available dialects of a scripting component. Each dialect
  910.         code is a short integer of type typeShortInteger.
  911.     
  912.         Errors:
  913.             badComponentInstance    invalid scripting component instance
  914.             errOSASystemError
  915.  
  916.         Type of a dialect info record containing at least keyOSADialectName
  917.         and keyOSADialectCode fields.
  918.  
  919.         keys for dialect info record, also used as selectors to OSAGetDialectInfo.
  920.  
  921.         Field of a typeOSADialectInfo record of typeChar.
  922.         Field of a typeOSADialectInfo record of typeShortInteger.
  923.         Field of a typeOSADialectInfo record of typeShortInteger.
  924.         Field of a typeOSADialectInfo record of typeShortInteger.
  925. */
  926. /*
  927. *************************************************************************
  928.     OSA Optional Event Handling Interface
  929. **************************************************************************
  930.     Scripting components that support the Event Handling interface have the 
  931.     kOSASupportsEventHandling bit set in it's ComponentDescription.
  932. *************************************************************************
  933. */
  934. /*
  935.         OSAComponentFunctionInline(kOSASelectSetResumeDispatchProc, 8);
  936.         This function is used to set the ResumeDispatchProc that will be used
  937.         by OSAExecuteEvent and OSADoEvent if either no event handler can be
  938.         found in the context, or the context event hander "continues" control
  939.         onward. The two constants kOSAUseStandardDispatch and kOSANoDispatch
  940.         may also be passed to this routine indicating that the handler registered
  941.         in the application with AEInstallEventHandler should be used, or no
  942.         dispatch should occur, respectively.
  943.     
  944.         Errors:
  945.             badComponentInstance    invalid scripting component instance
  946.             errOSASystemError
  947. */
  948. /*
  949.         Special ResumeDispatchProc constant which may be passed to 
  950.         OSASetResumeDispatchProc indicating that the handler registered
  951.         in the application with AEInstallEventHandler should be used.
  952.         
  953.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  954.                 doesn't allow pointer types to be assigned to an enum.  All
  955.                 constants must be assigned as enums to translate properly to
  956.                 Pascal.
  957. */
  958. /*
  959.         Special ResumeDispatchProc constant which may be passed to 
  960.         OSASetResumeDispatchProc indicating that no dispatch should occur.
  961.         
  962.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  963.                 doesn't allow pointer types to be assigned to an enum.  All
  964.                 constants must be assigned as enums to translate properly to
  965.                 Pascal.
  966. */
  967. /*
  968.         Special refCon constant that may be given to OSASetResumeDispatchProc
  969.         only when kOSAUseStandardDispatch is used as the ResumeDispatchProc.
  970.         This causes the standard dispatch to be performed, except the phac
  971.         handler is not called.  This is useful during tinkerability, when
  972.         the phac handler is used to lookup a context associated with an event's 
  973.         direct parameter, and call OSAExecuteEvent or OSADoEvent.  Failure to
  974.         bypass the phac handler would result in an infinite loop.
  975. */
  976. /*
  977.         OSAComponentFunctionInline(kOSASelectGetResumeDispatchProc, 8);
  978.         Returns the registered ResumeDispatchProc.  If no ResumeDispatchProc has
  979.         been registered, then kOSAUseStandardDispatch (the default) is returned.
  980.     
  981.         Errors:
  982.             badComponentInstance    invalid scripting component instance
  983.             errOSASystemError
  984. */
  985. /*
  986.         OSAComponentFunctionInline(kOSASelectExecuteEvent, 16);
  987.         This call is similar to OSAExecute except the initial command to
  988.         execute comes in the form of an AppleEvent.  If the contextID
  989.         defines any event handlers for that event, they are used to process
  990.         the event.  If no event handler can be found in the context
  991.         errAEEventNotHandled is returned.  If an event handler is found and
  992.         the hander "continues" control onward, the ResumeDispatchProc
  993.         (registered with OSASetResumeDispatchProc, above) is called given the
  994.         AppleEvent.  The result is returned as a scriptValueID.
  995.     
  996.         Errors:
  997.             badComponentInstance    invalid scripting component instance
  998.             errOSASystemError
  999.             errOSAInvalidID
  1000.             errOSAScriptError:        the executing script got an error
  1001.             errAEEventNotHandled:    no handler for event in contextID
  1002.     
  1003.         ModeFlags:
  1004.             kOSAModeNeverInteract
  1005.             kOSAModeCanInteract
  1006.             kOSAModeAlwaysInteract
  1007.             kOSAModeCantSwitchLayer
  1008.             kOSAModeDontReconnect
  1009.             kOSAModeDoRecord
  1010. */
  1011. /*
  1012.         OSAComponentFunctionInline(kOSASelectDoEvent, 16);
  1013.         This call is similar to OSADoScript except the initial command to
  1014.         execute comes in the form of an AppleEvent, and the result is an 
  1015.         AppleEvent reply record.  If the contextID defines any event handlers
  1016.         for that event, they are used to process the event.  If no event handler
  1017.         can be found in the context errAEEventNotHandled is returned.  If an
  1018.         event handler is found and the hander "continues" control onward, the
  1019.         ResumeDispatchProc (registered with OSASetResumeDispatchProc, above) is
  1020.         called given the AppleEvent.  The result is returned in the form of an
  1021.         AppleEvent reply descriptor. If at any time the script gets an error, or
  1022.         if the ResumeDispatchProc returns a reply event indicating an error,
  1023.         then the OSADoEvent call itself returns an error reply (i.e. OSADoEvent
  1024.         should never return errOSAScriptError).  Any error result returned by
  1025.         the ResumeDispatchProc will be returned by OSADoEvent.
  1026.     
  1027.         Errors:
  1028.             badComponentInstance    invalid scripting component instance
  1029.             errOSASystemError
  1030.             errOSAInvalidID
  1031.             errAEEventNotHandled:    no handler for event in contextID
  1032.     
  1033.         ModeFlags:
  1034.             kOSAModeNeverInteract
  1035.             kOSAModeCanInteract
  1036.             kOSAModeAlwaysInteract
  1037.             kOSAModeCantSwitchLayer
  1038.             kOSAModeDontReconnect
  1039.             kOSAModeDoRecord
  1040. */
  1041. /*
  1042.         OSAComponentFunctionInline(kOSASelectMakeContext, 12);
  1043.         Makes a new empty context which may be passed to OSAExecute or 
  1044.         OSAExecuteEvent.  If contextName is typeNull, an unnamed context is
  1045.         created. If parentContext is kOSANullScript then the resulting context
  1046.         does not inherit bindings from any other context.
  1047.     
  1048.         Errors:
  1049.             badComponentInstance    invalid scripting component instance
  1050.             errOSASystemError
  1051.             errOSAInvalidID
  1052.             errAECoercionFail:        contextName is invalid
  1053. */
  1054. #endif
  1055.  
  1056. #endif /* __SOMIDL__ */
  1057.  
  1058. #endif /* __OSA_IDL__ */
  1059.  
  1060.